Retry Policies

Retry policies allow workflow execution to repeat an operation when execution fails. Retries are particularly useful for operations that may fail temporarily, such as external service calls, network requests, AI provider calls, or other transient operations. In BindAI, retry behavior is handled by the workflow execution layer.

What Is a Retry Policy?

A retry policy defines how failed execution should be attempted again. Conceptually:

Execute Operation
       |
       v
    Success?
     /    \
   Yes     No
    |       |
Continue   Retry Policy
              |
              v
          Try Again

If a retry succeeds, normal workflow execution continues. If the configured retry limit is reached, the workflow enters its normal failure path.

Why Use Retries?

Retries are useful when an operation can reasonably succeed if attempted again. Common examples include:

External API calls
AI provider requests
Network operations
Database operations
Cloud services
External integrations
Temporary service failures

Retries should only be used when repeating the operation is safe.

Retry Policy Configuration

BindAI provides retry-policy configuration for controlling retry behavior. The retry policy currently defines configuration for:

Field	Default	Purpose
`max_attempts`	`3`	Maximum number of attempts
`delay_seconds`	`5`	Configured retry-delay value
`exponential_backoff`	`True`	Configures exponential-backoff behavior

The current executor uses max_attempts to control the number of attempts. The delay_seconds and exponential_backoff settings are currently defined as configuration fields but are not yet applied by the executor’s retry loop. Therefore, applications should not currently assume that these settings introduce an actual delay or exponential backoff.

How Retries Work

Retry handling occurs when workflow execution raises an exception. Conceptually:

Execute Operation
       |
       v
   Exception
       |
       v
Retry Policy Available?
     /          \
   No            Yes
   |              |
 Fail        Increment Attempt
                  |
                  v
             Limit Reached?
               /       \
             Yes        No
              |          |
             Fail     Execute Again

The workflow execution layer controls this process. A successful retry returns execution to the normal workflow path.

Maximum Attempts

max_attempts controls the maximum number of executions allowed for the failed operation. For example:

RetryPolicy(
    max_attempts=3,
)

represents:

Attempt 1
   |
 Failure
   |
Attempt 2
   |
 Failure
   |
Attempt 3
   |
 Failure
   |
Workflow Failure

The configured value represents the maximum number of attempts, including the initial attempt. Therefore:

max_attempts=1 means no retry
max_attempts=2 allows one retry
max_attempts=3 allows two retries

This distinction is important when configuring reliability behavior.

Successful Retry

If an operation fails initially but succeeds on a later attempt, normal workflow execution continues. Conceptually:

Attempt 1
   |
Failure
   |
Attempt 2
   |
Success
   |
Continue Workflow

The workflow does not treat the successful retry as a separate successful workflow. The operation has ultimately completed successfully.

Retry Without a Policy

If execution raises an exception and no retry policy applies, the failure follows the normal workflow error-handling path. Conceptually:

Execute Operation
       |
    Exception
       |
       v
No Retry Policy
       |
       v
Workflow Failure

Retries should therefore be configured intentionally for operations that are safe and useful to repeat.

Retry State

The workflow execution layer tracks retry progress while handling a failed operation. The current implementation maintains retry-attempt state internally during execution. This state is used to determine whether another attempt is permitted. Documentation should treat the retry counter and related execution-context fields as implementation details unless they are explicitly exposed as part of BindAI’s supported public API.

Retry Delay and Backoff

The retry policy currently defines:

delay_seconds = 5
exponential_backoff = True

However, these settings are not currently applied by the executor’s retry loop. The current behavior therefore retries immediately rather than waiting for the configured delay. Conceptually, a future delay-aware implementation could behave like:

Attempt 1
   |
Failure
   |
Wait
   |
Attempt 2
   |
Failure
   |
Longer Wait
   |
Attempt 3

Exponential backoff is commonly useful for external services because it reduces repeated requests during temporary failures. For the current BindAI implementation, however, delay_seconds and exponential_backoff should be considered configuration reserved for retry-delay behavior rather than active runtime features.

Retryable Exceptions

The current retry implementation does not define a built-in list of retryable exception types. When a retry policy applies, exceptions raised during node execution enter the retry handling. There is currently no documented configuration such as:

retry_on = (TimeoutError, ConnectionError)

Therefore, applications should not assume that only transient exceptions are retried. This makes it especially important to configure retries only around operations where repeated execution is safe.

Idempotency and Safe Retries

Retries can be dangerous for operations that produce side effects. For example:

Send Payment
     |
   Timeout
     |
   Retry

The timeout does not necessarily mean that the first operation failed. The external service may have completed the operation even though the response was not received. Repeating the operation could therefore produce an unintended duplicate. When using retries with external services, consider:

Idempotency
Duplicate requests
Transaction boundaries
External service behavior
Unique request identifiers
Partial completion
Provider-specific retry guidance

Read-only operations are generally easier to retry safely than irreversible side effects.

Retry vs Loop

Retries and loops both execute operations repeatedly, but they have different purposes.

Retry	Loop
Triggered by execution failure	Triggered by workflow logic
Repeats failed execution	Repeats intended workflow operations
Used for failure recovery	Used for business/process iteration
Controlled by retry configuration	Controlled by loop conditions
Usually operates around a failed operation	Represents repeated workflow behavior

Use a retry when an operation failed and another attempt may succeed. Use a loop when repetition is part of the intended workflow logic.

Retry vs Parallel Execution

Retry and parallel execution solve different problems. Parallel execution answers:

Which independent operations can proceed separately?

Retry answers:

What should happen when an operation fails?

They can be combined. For example:

Parallel
 /      \
A        B
|        |
Retry   Retry
 \      /
  Continue

Each independent branch can have its own failure and retry behavior according to the workflow configuration. Parallel execution itself does not provide automatic retry behavior.

Retry and Timeout

Retries and timeouts operate at different levels. A retry controls what happens after an operation fails. A timeout limits how long an operation or workflow is allowed to run, depending on the configured timeout scope. Conceptually:

Workflow
   |
   +--> Timeout
   |
   +--> Operation
           |
           +--> Retry

Combining the two can be useful for external operations that may temporarily fail but should not keep the workflow running indefinitely. The exact interaction between retry and timeout settings depends on the workflow executor’s implementation.

Failure After Retries

When all permitted attempts fail, the workflow follows its normal failure-handling path. Conceptually:

Retry Limit Reached
        |
        v
Workflow Failure
        |
        +--> Record Error
        |
        +--> Update Execution State
        |
        +--> Run Failure Handling
        |
        +--> Return Failed Result

The exact persistence, event, and history behavior depends on the workflow execution implementation. Retry handling should therefore be distinguished from the broader workflow failure lifecycle.

Compensation

Compensation is separate from retry behavior. A retry asks:

Should this failed operation be attempted again?

Compensation asks:

What should the workflow do when the overall operation ultimately fails?

For workflows that support compensation callbacks, compensation can be used as part of final failure handling. Conceptually:

Operation
   |
Failure
   |
Retry
   |
Failure Again
   |
Workflow Failure
   |
Compensation

Compensation should not be confused with retrying.

External Services

Retries are particularly useful around external services that may experience temporary failures. Examples include:

HTTP APIs
AI providers
Databases
Cloud services
SaaS integrations
Network services

However, external providers often have their own rate limits and retry recommendations. An application should consider the provider’s documented behavior before configuring aggressive retries.

AI Provider Retries

AI provider requests may fail because of temporary network conditions, service availability, or provider-side errors. A retry can sometimes recover from such failures:

Agent Request
     |
   Failure
     |
    Retry
     |
   Success

However, not every provider error should necessarily be retried. For example, configuration errors, invalid requests, or authentication failures are generally different from temporary service failures. Because the current BindAI retry implementation does not filter exception types, applications should configure retry policies carefully.

Database Retries

Database operations can also encounter transient failures. Potential examples include:

Temporary connection failures
Network interruptions
Connection pool exhaustion
Temporary service unavailability

However, retrying database writes requires particular care because the original operation may have succeeded even if the client did not receive confirmation. Transaction and idempotency semantics should be considered before retrying write operations.

External Integration Retries

Connections to external services may also be wrapped by retry behavior. For example:

Workflow
   |
   v
External Integration
   |
Failure
   |
Retry
   |
Success

The integration should be designed so that repeated requests do not accidentally create duplicate side effects.

Retry and Workflow State

Retrying an operation should not be confused with starting a new workflow. Conceptually:

Workflow Execution
       |
       +--> Attempt 1
       |
       +--> Attempt 2
       |
       +--> Attempt 3
       |
       v
Continue or Fail

The retry occurs within the existing workflow execution. Applications should therefore design state updates carefully so that a failed attempt does not leave inconsistent state for the next attempt.

State and Side Effects

Consider:

Attempt 1
   |
Write State
   |
Failure
   |
Attempt 2

If the first attempt partially modified state, the second attempt may observe that modified state. For this reason, retryable operations should ideally be:

Idempotent
Transactional where appropriate
Safe to repeat
Explicit about partial state
Resistant to duplicate side effects

This is especially important for external APIs, payments, messaging, and database writes.

Testing Retry Behavior

Retry behavior should be tested explicitly. Important cases include:

Operation succeeds immediately
Operation fails once and then succeeds
Operation fails multiple times and then succeeds
Operation fails on every attempt
Retry policy is absent
max_attempts=1
Maximum attempts are reached
An exception is raised during execution
Retried operations interact with external services
Retried operations modify state
A workflow ultimately enters failure handling

A useful test pattern is to create an operation that intentionally fails a controlled number of times before succeeding. Conceptually:

Call 1 → Failure
Call 2 → Failure
Call 3 → Success

This verifies that the configured attempt limit is respected.

Testing Side Effects

Retry tests should also verify that repeated execution does not create unintended side effects. For example:

Attempt 1
   |
External Request
   |
Failure/Timeout
   |
Attempt 2
   |
External Request

Tests should determine whether the external operation is safe to repeat. For important integrations, idempotency behavior should be tested separately from the retry mechanism itself.

Observability

Retry behavior is easier to diagnose when execution records contain useful information. Useful observability data can include:

Operation name
Attempt number
Failure reason
Total attempts
Final status
Execution duration
Retry-related events
External service response information

The exact observability APIs depend on the current BindAI implementation.

Best Practices

Set a reasonable max_attempts.
Use retries only where repeated execution is safe.
Prefer idempotent operations for retryable work.
Be especially careful with external side effects.
Do not assume every exception is transient.
Remember that the current implementation does not filter exception types.
Do not assume delay_seconds currently pauses execution.
Do not assume exponential_backoff is currently active.
Consider timeouts for operations that may take a long time.
Respect external-service rate limits.
Test both successful and exhausted retries.
Test state and side effects across repeated attempts.
Keep retry behavior separate from business-logic loops.

Current BindAI Scope

BindAI currently provides retry behavior as part of workflow execution. The current retry implementation supports:

Configurable maximum attempts
Retry handling for node execution failures
Immediate re-execution after failure
Normal workflow continuation after successful retry
Normal workflow failure handling after attempts are exhausted

The retry policy also defines:

delay_seconds
exponential_backoff

but these settings are not currently applied by the executor’s retry loop. The current implementation also does not provide documented exception-type filtering for retry behavior.

API Accuracy

Retry behavior is part of the workflow execution system. Internal implementation details such as:

Retry counters
Execution-context fields
Executor retry loops
Internal failure state
Persistence operations
Retry event internals

should only be treated as public APIs when they are explicitly exposed and supported by the current BindAI release. This documentation therefore describes the observable retry behavior rather than requiring applications to interact directly with internal execution state.

Summary

BindAI retry policies allow failed workflow operations to be attempted again. The current implementation uses max_attempts to determine how many attempts are allowed, including the initial attempt. For example:

max_attempts=3

Attempt 1 → Failure
Attempt 2 → Failure
Attempt 3 → Success

If an operation succeeds on a retry, normal workflow execution continues. If all permitted attempts fail, the workflow enters its normal failure-handling path. The current retry loop retries immediately. Although delay_seconds and exponential_backoff are defined by the retry policy, they are not currently applied by the executor. The implementation also does not currently provide exception-type filtering. Retries are therefore a simple executor-level failure-recovery mechanism. They should be used carefully, particularly around external services and operations with side effects.

​Retry Policies

​What Is a Retry Policy?

​Why Use Retries?

​Retry Policy Configuration

​How Retries Work

​Maximum Attempts

​Successful Retry

​Retry Without a Policy

​Retry State

​Retry Delay and Backoff

​Retryable Exceptions

​Idempotency and Safe Retries

​Retry vs Loop

​Retry vs Parallel Execution

​Retry and Timeout

​Failure After Retries

​Compensation

​External Services

​AI Provider Retries

​Database Retries

​External Integration Retries

​Retry and Workflow State

​State and Side Effects

​Testing Retry Behavior

​Testing Side Effects

​Observability

​Best Practices

​Current BindAI Scope

​API Accuracy

​Summary